home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1996 February / EnigmA AMIGA RUN 04 (1996)(G.R. Edizioni)(IT)[!][issue 1996-02][Skylink CD III].iso / earcd / gnu / gcc263-utils.lha / gnu / README-2.6.3 < prev   
Text File  |  1994-12-11  |  34KB  |  871 lines
  1. Short: gcc v2.6.3 - C/C++/ObjC Compiler set for AmigaDOS
  2. Type: dev/gcc
  3. Uploader: phb@colombo.telesys-innov.fr
  4. Author: phb@colombo.telesys-innov.fr
  5.  
  6. This directory contains the 2.6.3 release of the GNU C compiler.
  7.  
  8. The GNU C compiler is free software.  See the file COPYING for copying
  9. permission.
  10.  
  11. ===============
  12. How to get help
  13. ===============
  14.  
  15. There's an amiga-gcc mailing list running in Finland, read README-LIST file.
  16. This is the preferred place to ask for help since I'm on this list and
  17. every GCC developers also, libnix & ixemul authors, etc...
  18.  
  19. Short: send an email to listserv@lists.funet.fi, and put in body:
  20.     subscribe amiga-gcc-port your_first_name your_last_name
  21.  
  22. Otherwise you can contact me at:
  23.  
  24.     Philippe BRAND
  25.     Fidonet: Ramses The Amiga Flying BBS 2:320/104.21
  26.     Email:   phb@colombo.telesys-innov.fr (ONLY for personal email).
  27.     Ftp:     colombo.telesys-innov.fr:/pub/amigados-gnu
  28.              or /pub/incoming/uploads for uploads.
  29.  
  30. Note: I'll forward any question to this mailing-list, but please use it
  31. directly, except when you send files, in this case send them to my ftp site.
  32.  
  33. Note2: ftp.funet.fi mirrors my amigados-gnu tree. Using ftp.funet.fi is
  34. preferable as they have much more bandwidth.
  35.  
  36. ============
  37. Requirements
  38. ============
  39.  
  40. - Systems:
  41. Any Amiga (ranging from A1000 up to A4000/40, including CD-32 & SX-1) will
  42. run amigados-gnu utilities.
  43.  
  44. - Memory:
  45. A minimum of 4MB free memory is needed in order to compile small/medium
  46. projects.
  47. More memory will be needed for large projects, such as recompiling gcc
  48. itself.
  49. Gigamem is known to work with GCC so *maybe* less memory will work. But in this
  50. case, you'll need an MMU equiped amiga (A3000,A4000/40, etc...).
  51. VMM40 (Public Domain Virtual memory manager) is also known to work with GCC.
  52.  
  53. - OS:
  54. Starting from this release, 1.3 systems are not longer supported.
  55. Gcc runs fine on all other systems, starting from 2.04 up to 3.1 (40.68).
  56.  
  57. - Disk Space;
  58. An installation of gcc requires the use of a hard disk. Approximately 10MB is
  59. required at present to install the compiler and utilities required to use it.
  60. In addition 3MB is required for the Commodore Developer Kit, which is required
  61. to be able to compile AmigaDOS specific programs. This kit is available direct
  62. from Commodore-Amiga.
  63.  
  64. ==========================
  65. What's new in this release
  66. ==========================
  67.  
  68. 2.6.3
  69.  
  70. - Read FSF NEWS-2.6.1 file included.
  71. - As always, generic bugs fixed (see Changelog in gcc sources for details).
  72. - q_anote package replaced by FSF listing shell script, need awk.
  73. - new as/ld/size/nm/ranlib, made by Raphael Luebbert
  74. - new environnement variables GCCPRIORITY and GCCSTACK, see below.
  75. - all programs recompiled using 2.6.3 compiler.
  76. - mit2mot & mot2mit, convert asm syntax between Motorala and MIT syntaxes.
  77. - all programs hold AmigaDOS compatible $VER string.
  78.  
  79. =================================
  80. What was new in previous releases
  81. =================================
  82.  
  83. 2.6.2
  84.  
  85. - internal release only.
  86.  
  87. 2.6.1
  88.  
  89. - Read FSF NEWS-2.6.1 file included.
  90. - As always, generic bugs fixed (see Changelog in gcc sources for details).
  91. - new option -priority in gcc allowing process priority setting.
  92. - new specs file, inlines/protos and libamiga done by Gunther Nikl. See note
  93.   below.
  94. - new libnix version by Matthias Fleischer & Gunther Nikl.
  95. - new ixemul version by Raphael Luebbert.
  96. - stripc program to strip all uneccessary stuff from headers by Chris Metcalf,
  97.   submitted by Lars Hecking.
  98. - q_anote, anotate assembly files mixing C source code, submitted by Walter
  99.   Harms (Walter.Harms@arbi.informatik.uni-oldenburg.de), written by 
  100.   Mike Albaugh (albaugh@agames.com). See note below.
  101. - new assembler, as-2.5, using new BFD (Binary File Descriptor), made by
  102.   Raphael Luebbert.
  103.  
  104. 2.6.0
  105.  
  106. - Read FSF NEWS-2.6.0 file included.
  107. - Extensive internal compiler bugs fixed (see ChangeLog in gcc sources for
  108.   details), tons of bugs fixed for C++ support.
  109. - ld changed (see note for ld below).
  110. - new ixemul.library, with optimized versions for accelerated Amigas, see
  111.   README-ixemul & ixemul.guide for more informations.
  112. - new C library (libnix) disabling use of ixemul.library for generated
  113.   programs (best use for AmigaDOS specific programs). Full ANSI compliant, see
  114.   README-libnix & libnix.guide for more informations.
  115. - revised inline headers in accordance with new ixemul.library.
  116. - libamiga.a is now distributed with gcc-2.6.1.
  117. - as v2.3 is included, along with a macro-assembler (gasp).
  118. - stderrfix.o (see below) patch applied.
  119. - Upgrade to libg++-2.6.
  120. - Gcc now supports $VER string for AmigaDOS version compatibility.
  121.  
  122. 2.5.8
  123.  
  124. - Read FSF NEWS-2.5.8 file included.
  125. - ld behavior over symbols changed (see note below).
  126. - added flavors so that linker will take appropriate libraries according to
  127.   gcc options (m68020 libraries/baserel libraries, etc...).
  128. - gpc (GNU-Pascal) v1.03 added.
  129. - all utilities recompiled with gcc-2.5.8.
  130. - plain 68000 and 68020+68881 versions of all binaries available.
  131. - More internal compiler bugs fixed (see ChangeLog in gcc sources for details),
  132.   some for C++ support.
  133. - GCC-Install script fixed by Claus Deckhut (to be used with full distrib).
  134. - Upgrade to libg++-2.5.3.
  135. - trace.c updated by J. Hoehle to avoid buffer overflows.
  136.  
  137. 2.5.7:
  138.  
  139. - Read FSF NEWS file included.
  140. - More internal compiler bugs fixed (see ChangeLog in gcc sources for details),
  141.   a lot for C++ support.
  142. - Fred Fish seems to have finally found an annoying bug which prevented
  143.   to compile a resident version of GCC, or to compile resident programs. But
  144.   don't try it anyway 'cause there's still lack of library support as for now.
  145. - Man command now works, this one was my fault (well in fact like others ;-),
  146.   fix done by Tom Haiko.
  147. - Infoview works also, it was an internal path problem.
  148. - libamy.a HAS TO BE RENAMED to libamiga.a because new ld won't find libamy.a
  149. - upgrade to new C++ library v2.5.1.
  150.  
  151. =======
  152. Authors
  153. =======
  154.  
  155. Gcc v2.2.2 port:   Markus Wild
  156. Gcc v2.3.3 port:   Markus Wild
  157. Gcc v2.4.5 port:   Philippe Brand, Lars Hecking, Fred Fish
  158. Gcc v2.5.0 and up: Philippe Brand, Fred Fish, Leonard Norrgard 
  159.  
  160. Ixemul.library:    Markus Wild, Leonard Norrgard, Raphel Luebbert,
  161.                    Stephan Isthesin.
  162. Libnix:            Matthias Fleischer, Gunther Nikl
  163.  
  164. Thanks to all amiga-gcc-port mailing-list users for their reports and support
  165. for a better amigados-gcc and documentation.
  166.  
  167. =======
  168. Sources
  169. =======
  170.  
  171. These archives should contain everything necessary to get you going, they
  172. don't include sources for all tools (have a look at end of paragraph).
  173.  
  174. As stated by Richard Stallman of the FSF:
  175.  
  176. "The GPL says that any distribution of binaries must contain either the
  177. source code or a written offer to supply source code (see the GPL for
  178. details of what is required)."
  179.  
  180. If you're interested in the sources required to rebuild gcc, get the
  181. gcc263-src.lha, which hold sources for gcc. Those archives should be stored
  182. either the same ftp site you got this binary distribution from (if they're
  183. not, tell the manager of that ftp site, as this is a requirement of the
  184. GNU Copyright LICENSE), either at ftp.gnu.ai.mit.edu:/pub/gnu, either on
  185. Ramses BBS (phone numbers listed below).
  186.  
  187. If you have those archives, you can skip to next paragraph. If you have
  188. original FSF sources, you'll have to apply the gcc patch-file in src-patches/,
  189. and configure for `amigados'. Please note that you should have at least 40MB
  190. left or your HD and 8MB of memory minimum in order to rebuild gcc up to stage3.
  191. An accelerated Amiga is welcome, as it took me 4,5 hours to generate a single
  192. pass. So 3 passes makes 4,5 x 3 = 13,5 hours.
  193.  
  194. Sources for other tools only included as binaries are available separately
  195. in self-contained archives, usually having their name into the archive-name.
  196.  
  197. File                What
  198.  
  199. gcc263-src.lha            C/C++/ObjC compiler sources & diff file
  200. libnix-0.6.lha            libnix sources and binaries
  201. ixemul-40.4-src.lha        ixemul sources and libraries
  202. binutils-1.8.x-src.lha        Sources for ld
  203. binutils-2.5.2-src.lha        Sources for ar/ranlib & diff file
  204. gdbm-1.7.3-src.lha        Sources for gdbm & diff file
  205. make-3.71-src.lha        make sources & diff file
  206. patch-2.1-src.lha        patch sources, needed to apply diff files
  207. sed-2.05-src.lha        sed sources & diff file
  208. gawk-2.15.5-src.lha        GNU awk sources & diff file
  209. diffutils-2.7-src.lha        diff utility sources & diff file
  210. fileutils-3.11-src.lha        file utilities sources & diff file
  211. sh-utils-1.12-src.lha        shell utilities sources & diff file
  212. textutils-1.11-src.lha        text utilities sources & diff file
  213. findutils-4.1-src.lha        find sources & diff file
  214. grep-2.0-src.lha        grep sources & diff file
  215. bison-1.22-src.lha        bison (yacc replacement) sources & diff file
  216. flex-2.4.7-src.lha        flex (lex replacement) sources & diff file
  217. texinfo-3.1-src.lha        texinfo (includes makeinfo) sources & diff file
  218. gzip-1.2.4-src.lha        gzip sources & diff file
  219. tar-1.11.2-src.lha        gtar sources & diff file
  220. cpio-2.3-src.lha        cpio sources & diff file
  221. gdbm-1.7.3-src.lha        database manip. library sources & diff file
  222. termcap-1.2-src.lha        termcap library sources & diff file
  223. libm-5.6-src.lha        BSD mathematic library sources & diff file
  224.  
  225.  
  226. NOTE:
  227. All sources archives are amiga ready, and amiga specific diff file located
  228. in 'amiga' directory. To recompile a tool, just run a 'configure amigados'
  229. then a 'make'.
  230. Exceptions are libnix, ixemul which have their own archives, both binary &
  231. sources.  On Aminet sites, libnix & ixemul in /pub/amiga/dev/gcc.
  232.  
  233. =====
  234. Where
  235. =====
  236.  
  237. **** All GNU sources & binaries are available on:
  238.  
  239. - ftp.telesys-innov.fr, primary Amiga-GNU FTP site, and its mirror ftp.funet.fi
  240.   which is MUCH faster than my own site. Please use it at first choice.
  241.     in /pub/amigados-gnu
  242.  
  243. - Aminet sites (wuarchive.wustl.edu and mirrors such as ftp.luth.se)
  244.     in /pub/amiga/dev/gcc
  245.  
  246. - Ramses The Amiga Flying BBS  +33-1-60037015  HST Dual v32 terbo 4800-21600
  247.                                +33-1-60037713  SupraFax v32bis    4800-14400
  248.                                +33-1-60037716  Tornado v22bis     1200-2400
  249.     in Topic "Development", Area "Gcc"
  250.  
  251. - FreshFish CDs from Fred Fish           Amiga Library Services
  252.     in :GNU/bin, :GNU/src, :GNU/lib dirs.  610 N. Alma School Road, Suite 18
  253.                        Chandler, AZ 85224-3687
  254.                        USA
  255.                        Fax: (602) 917-0917 (no voice phone
  256.                        orders, FAX only)
  257.  
  258. **** GNU source code is available on:
  259.  
  260. - same FTP site you've taken these archives
  261.  
  262. - gnu.prep.ai.mit.edu 18.71.0.38
  263.     in /pub/gnu
  264.  
  265. - Ramses The Amiga Flying BBS
  266.     in Topic "AmigaUnix/Unix/Linux/NetBSD", Area "Gnu Source Code"
  267.  
  268. - FreshFish from Fred Fish
  269.     in :GNU/src
  270.  
  271. ======
  272. Layout
  273. ======
  274.  
  275. Gcc-2.6.3 is split up into 14 archives:
  276.  
  277. gcc263-readme.lha    holds readmes files (include installation notes).
  278. gcc263-base.lha         basic gcc distribution, hold necessary files.
  279. gcc263-c.lha        C compiler.
  280. gcc263-c-020.lha    68020+68881 version of C compiler.
  281. gcc263-c++.lha        C++ compiler, headers and libraries.
  282. gcc263-c++-020.lha    68020+68881 versions of C++ compiler.
  283. gcc263-objc.lha        Objective-C compiler, header and libraries.
  284. gcc263-objc-020.lha    68020+68881 versions of Objective-C compiler.
  285. gcc263-doc.lha        Gcc AmigaGuide(tm) documents & manpages.
  286. gcc263-utils.lha    Useful utilities needed for development.
  287. gcc263-utilsdoc.lha    Utilities documentation (guide & manpages).
  288. gcc263-texi.lha        All Texinfo documents.
  289. gcc263-diffs.lha    Diff files for all binaries.
  290. gcc263-src.lha        Source for gcc-2.6.3 plus diff file.
  291.  
  292. Name            What                    Where    
  293. ----            ----                    -----
  294.  
  295. COPYING            GNU LICENSE, read!!            All archives
  296. COPYING.LIB        GNU LIBRARY LICENSE, read!!        All archives
  297. README-2.6.3        this file                All archives
  298. NEWS-2.6.3        What's new in gcc-2.6.3            gcc263-base
  299. Installer        Commodore installer utility        gcc263-base
  300. GCC-Install        Installer script to configure gcc    All archives
  301. envarc/            global environment variables you should
  302.             have set when using this programming    gcc263-base
  303.             environment
  304. include/        non-amiga specific C/C++ headers    gcc263-base
  305. os-include/proto    amiga specific protos headers.        gcc263-base
  306. os-include/inline    amiga specific inline C headers. Add    gcc263-base
  307.             Commodore headers!!        
  308. os-lib/            amiga specific libraries        gcc263-base
  309. guide/            Docs in AmigaGuide(tm) format        gcc263-doc
  310. man/            this is the root for tons of man pages    gcc263-doc
  311. bin/            this is /bin, and contains all         gcc263-c
  312.             binaries of this distribution that    gcc263-c++
  313.             are meant to be directly invoked by    gcc263-utils
  314.             the user (contrary to the executables
  315.                  in lib/gcc-lib/, that are meant to be
  316.             invoked by a driver program like gcc)
  317. lib/            normal (not base relatives) libraries    gcc263-base
  318. lib/libm020/        normal 68020 libraries            gcc263-base
  319. lib/libb/        base relatives libraries        gcc263-base
  320. lib/libb/libm020/    base relatives using 68020 libraries    gcc263-base
  321. lib/libnix/        Non-ixemul libraries            gcc263-base
  322. lib/libm020/libnix/    Non-ixemul 68020 libraries        gcc263-base
  323. lib/libb/libnix/    Non-ixemul base relatives libraries    gcc263-base
  324. lib/libb/libm020/libnix    Non-ixemul base relatives 68020 libs    gcc263-base
  325. lib/gcc-lib/        home of compilers called by gcc        gcc263-c
  326.                                 gcc263-c++
  327.                                 gcc263-objc
  328. ixpipe/            a pipe handler needed by the library    gcc263-base
  329. libs/            ixemul.library                gcc263-base
  330. rexx/            ARexx wrappers for gcc and g++        gcc263-base
  331. src-patches/        source patches                gcc263-diffs
  332. geninline/        Perl scripts to generate inline headers    gcc263-base
  333.             and -lamy glue
  334.  
  335. ==============
  336. Inline-Headers
  337. ==============
  338.  
  339. Since I'm not able to redistribute amiga header files, you will have to get
  340. them directly from Commodore, unless you're an official registrated Amiga
  341. developer. In order to generate inline-headers, follow these steps (provided
  342. amiga headers and fd files are in os-include). You don't have to generate them
  343. if you use OS3.1 (40.13 headers).
  344.  
  345. 1) First method:
  346.  
  347. CLI> stack 100000
  348. CLI> Assign INCLUDE: GCC:os-include
  349. CLI> Assign FD: INCLUDE:fd
  350. CLI> Makedir INCLUDE:inline
  351. CLI> cd USR:bin/geninline
  352. CLI> gen31
  353.  
  354. This will create all inline-headers. If you have 2.0 headers, use gen20
  355. instead, if you have 3.0, use gen30, if you have 6.4, send it to me ;-)
  356.  
  357. NOTE: perl scripts do not handle correctly AmigaDOS include files, which
  358. seems to mean they are somewhat broken. If someone could work on this...
  359.  
  360. 2) Second method:
  361.  
  362. Use fd2inline, which you can find on Aminet in dev/gcc.
  363.  
  364. ===============
  365. Amiga Libraries
  366. ===============
  367.  
  368. Starting from this release an AmigaDOS compliant library is provided,
  369. thanks to libnix authors (Matthias Fleischer and Gunther Nikl).
  370.  
  371. Anyway if you want to rebuild one, there are two methods:
  372.  
  373. 1) Using hunk2gcc; the AmigaDOS object converter made by Markus Wild. To
  374. achieve this, simply grab a copy of latest amiga.lib (from Commodore
  375. Development Kit) and make a new directory where you want your converted
  376. object files to go, cd into it, and enter
  377.  
  378.   hunk2gcc amiga.lib [..further libs if you like..]
  379.  
  380. This generates an a.out object file for every program unit present in the
  381. hunk file (in this case, from amiga.lib).
  382.  
  383. As the final step convert all those files into an a.out style library by
  384. issuing:
  385.  
  386.   ar qc libamiga.a obj.*
  387.   ranlib libamiga.a
  388.  
  389. The ranlib run builds a symbol table in the archive, and makes accesses to
  390. the library much faster.
  391.  
  392. 2) Creating a libamiga.a library with libnix is fairly easy, but takes some
  393. time. Just uncompress sources.lha from libnix distribution and run a
  394. 'make libamiga.a'.
  395.  
  396. NOTE:
  397.  
  398. As long as you make no AmigaDOs specific calls, you can create a dummy library
  399. using:
  400.  
  401.   cat "int dummy;" >dummy.c
  402.   gcc -c dummy.c
  403.   ar crv libamiga.a dummy.o
  404.   mv libamiga.a gcc:lib
  405.  
  406. A small libamiga.a (dummy) is also provided with libnix.
  407.  
  408. ============
  409. Installation
  410. ============
  411.  
  412. 1) If this is your first installation of GCC, follow these steps;
  413.  
  414. - You need first to create a directory gnu on your hard-disk and unarchive
  415. first part:
  416.     CLI> cd place_with_lot_of_space
  417.     CLI> makedir gnu
  418.     CLI> lha x gcc263-base.lha
  419.  
  420. - Now you have to append gnu/s/user-startup to your s:user-startup file
  421. (replace Devel:GNU by your own gnu path). Execute it in order to get new
  422. assigns:
  423.     CLI> execute gnu/s/user-startup
  424.  
  425. - Copy gnu/envarc to ENVARC:
  426.     CLI> copy gnu/envarc/#? ENVARC:
  427.  
  428. - C-compiler is needed so unarchive C compiler part (Users with
  429. accelerated amigas can unarchive gcc263-c-020 part instead) :
  430.     CLI> lha x gcc263-c.lha  (or gcc263-c-020)
  431.  
  432. - If you want to have Gcc documentation on-line, unarchive doc part:
  433.     CLI> lha x gcc263-doc.lha
  434.  
  435. - If you want to do C++, unarchive C++ part (Users with
  436. accelerated amigas can unarchive gcc263-c++-020 part instead) :
  437.     CLI> lha x gcc263-c++.lha (or gcc263-c++-020)
  438. Please not that 68020+68881 versions have '.020' extension in GNU:bin.
  439.  
  440. - If you want to do Objective-C, unarchive Objective-C part (Users with
  441. accelerated amigas can
  442.  unarchive gcc263-objc-020 part instead) :
  443.     CLI> lha x gcc263-objc.lha (or gcc263-objc-020)
  444.  
  445. - If you want additional utilities (recommended for Unix compatibility),
  446. unarchive utils part:
  447.     CLI> lha x gcc263-utils.lha
  448.  
  449. - If you want all utilities documentation no-line, unarchive utils-doc
  450. part:
  451.     CLI> lha x gcc263-utilsdoc.lha
  452.  
  453. - Because some programs are normally link to others, please run script:
  454.     CLI> sh /gnu/s/restorelinks
  455.   Or if you don't want to use makelink but rather copy file, run script:
  456.     CLI> sh /gnu/s/restorelinks copy
  457.  
  458. - If you want to rebuild all distribution, you'll have to unarchive
  459. diff part:
  460.     CLI> lha x gcc263-diffs.lha
  461.  
  462. - If you want to build Postscipt files for Gcc documention, unarchive
  463. texinfo part:
  464.     CLI> lha x gcc263-texi.lha
  465.  
  466. - Now skip to next paragraph and happy compiling!
  467.  
  468. 2) If you "upgrade" your gcc environment from v2.5.x, just unarchive first
  469.    2 archives as it would normally include all what you need (thus gcc263-base
  470.    and gcc263-c). Make sure you delete your previous ixemul.library
  471.    wherever it is (usually LIBS:).
  472.  
  473. NOTE:  new version of ixemul.library is provided, make sure you don't have
  474. another copy somewhere which may conflict with gcc.
  475.      
  476. =============================
  477. Your first C program with gcc
  478. =============================
  479.  
  480. What about a nice Hello World ?
  481.  
  482.     #include <stdio.h>
  483.  
  484.     main()
  485.     {
  486.       printf("Hello World!\n");
  487.     }
  488.         
  489. This was pretty simple ;-) Now we have to compile it.     
  490. There's a lot of options in gcc but simplest way to compile this would be:
  491.  
  492. CLI> gcc -o hello hello.c
  493.  
  494. Simple ?
  495.  
  496. Here's more options.
  497.  
  498. Target processor for Motorola family:
  499. You can compile plain 68000 code, 68020, 68030, 68040, 68881 (have a look at
  500. GCC documentation, either in info or AmigaGuide format, chapter Invoking Gcc/
  501. SubModel Options/M680X0 Options for Motorola specific compilation flags).
  502.  
  503. CLI> gcc -m68020 -m68881 -o hello hello.c
  504.  
  505. This will compile your programs using 68020 code and direct calls to
  506. math-processor, and will link with accelerated libraries, located in
  507. GCC:lib/lib020.
  508.  
  509. Optimization:
  510. Either you don't want optimization, or you can provide -O, which will 
  511. optimize your code, or if you really want top optimization, use -O2 flag (for
  512. more discussion about optimization, read info or AmigaGuide doc chapter
  513. Invoking Gcc/Optimize Options). There's now even a -O3 optimization option,
  514. which will go even further.
  515.  
  516. CLI> gcc -O2 -o hello hello.c
  517.  
  518. You'll never have a "Hello World" program running so fast ;-)
  519.  
  520. Code generation:
  521. Perhaps you want to generate resident programs.
  522. Flag is -resident, at compile and link stage.
  523.  
  524. CLI> gcc -resident -o hello hello.c
  525.  
  526. Of course you can mix all options, resulting in:
  527.  
  528. CLI> gcc -O2 -m68020 -m68881 -resident -o hello hello.c
  529.  
  530. This will make a 68020+68881 executable highly optimized and resident.
  531.  
  532. IMPORTANT:
  533. If you only use AmigaDOS functions or you don't want to use ixemul for
  534. philosophical reasons, you can get rid of ixemul.library with:
  535.  
  536. CLI> gcc -noixemul -o foobar foobar.c
  537.  
  538. provided you have libnix distribution (included with 2.6.3 distribution).
  539.  
  540. ================
  541. Ixemul vs Libnix
  542. ================
  543.  
  544. Starting with 2.6.1 version of amigados-gcc, two C libraries are provided.
  545.  
  546. First one is using ixemul.library Amiga shared-library at run-time. This
  547. library makes it possible to easily convert Unix(tm) programs to AmigaDOS,
  548. and made for example possible gcc on AmigaDOS. Have a look at ixemul.guide
  549. for further informations.
  550.  
  551. Second one is an ANSI-C compliant library which is better suited for
  552. AmigaDOS specific development, thus not using any Unix specific routines.
  553.  
  554. Note that you can develop AmigaDOS specific programs with ixemul.library,
  555. but at the cost of an extra 200KB memory taken by shared library.
  556.  
  557. ===============================
  558. Redirection with ixemul.library
  559. ===============================
  560.  
  561. A common problem seen with amigados-gcc is bad redirection to sderr.
  562.  
  563. The fact is that ixemul.library takes stderr from the pr_CES field
  564. in the process structure. The field was added in 2.0. If the field
  565. is not set, then ixemul uses stdout, instead. The trouble is that this
  566. field must be set by the shell, and the only shell that does so is
  567. WShell!
  568.  
  569. The rationale behind ixemul.library working this way is that
  570. "run <NIL: >NIL: cmd" will detach your process from the terminal, so
  571. that you can close the initial CLI window after startup.
  572.  
  573. In any case, there is a workaround for the problem that was posted to the
  574. list a while back: compile your main program using the -Dmain=mymain
  575. option, then link with stderrfix.o to provide the actual main that will
  576. do the magic that creates an stderr stream that is different from
  577. stdout. Along with the C version a C++ version is included and was used to
  578. compile groff.
  579.  
  580. Thanks to Kriton Kyrimis for this explanation and patch.
  581. stderr fixes can be found in GNU:stderrfix (srcs-) and GNU:lib (.o files).
  582.  
  583. =====
  584. ARexx
  585. =====
  586.  
  587. The provided ARexx scripts have been contributed by Loren J. Rittle.
  588. If you like ARexx, they're an alternate way of calling gcc. They 
  589. automatically make sure you're using a large enough stack setting, and 
  590. enable you to compile C++ programs with less obscure options. This 
  591. approach is furthermore useful if you're not able to use the g++ /bin/sh
  592. script.
  593.  
  594. ===============
  595. gcc versus gccv
  596. ===============
  597.  
  598. gccv stands for a gcc using vfork() to spawn a new process, and then calling
  599. the new execve() function in ixemul.library to call its subcompilers. Gcc
  600. continues to using the more system friendly RunCommand() function in
  601. dos.library to start subcompilers. Gccv has the advantage of being able to
  602. work with interprocess pipes, thus (provided you have the memory ;-)), you're
  603. able to do
  604.  
  605.     gccv -pipe your_program.c
  606.  
  607. causing the preprocessor (cpp), the C-compiler (cc1) and the assembler (as)
  608. to run at the same time, passing intermediate files thru internal pipes 
  609. instead of using temporary files.
  610.  
  611. As long as you don't want that feature (ok, playing with certain make tools
  612. also requires gccv) you're safe using gcc.
  613.  
  614. ==========
  615. stack size
  616. ==========
  617.  
  618. You need to have a 50.000 stack size in order to compile with GCC. This should
  619. be enough for most projects. Note than while recompiling gcc with itself it
  620. has taken more than 300KB stack. Stack can grow due to source complexity.
  621. Don't be afraid of it.
  622.  
  623. To set the stack size, see the AmigaDOS Command 'stack'. 
  624.  
  625. To use ar and/or ranlib, 50KB is the minimum acceptable. You should have a
  626. much larger stack, if you use larger libraries.
  627.  
  628. Starting with 2.6.3 a new environnement variable, GCCSTACK, enables gcc to
  629. read this variable and set stack upon startup. Thus now no need to set stack
  630. to huge values, only gcc/ld/cpp/cc1#? will automatically set new stack,
  631. according to GCCSTACK variable.
  632.  
  633. Simply commit a: 
  634.     setenv GCCSTACK value
  635. to set gcc stack to value.
  636.  
  637. Benefits: huge memory savings.
  638.  
  639. ========
  640. priority
  641. ========
  642.  
  643. Starting also with 2.6.3 a new environnement variable, GCCPRIORITY, let you
  644. specify a default process priority for GNU compiler. Setting it to -1 enable
  645. your Amiga to do something else while compiling :-)
  646.  
  647. ===========
  648. C++ headers
  649. ===========
  650.  
  651. With AmigaDOS it makes no difference whether a name has capital or lower-case
  652. letters in names when finding files (i.e. it is case insensitive), you'll 
  653. certainly run into problems with some headers, including String.h and normal
  654. string.h. My suggestion for now is to add to C++ "faulty" header filename an
  655. "_" in front of it, thus String.h would become _String.h. Sorry for
  656. inconvenience. (thanks to Dirk Nehring for reminding me this anoying
  657. "feature").
  658.  
  659. =======
  660. Patches
  661. =======
  662.  
  663. Includes:
  664.  
  665.     Jörg Höhle
  666. hoehle@inf-wiss.uni-konstanz.de
  667.  
  668. There is a conflict between the Amiga and the UNIX definition of the
  669. timeval structure.  Markus Wild proposed in gcc233 to patch the Amiga
  670. devices/timer.h file so that it loads the UNIX sys/time.h file (and
  671. thus tons of other files) (see os-include/devices/timer.mwild.path). I
  672. suggest that sys/time.h and devices/timer.h be modified to detect each
  673. other and use whichever structure was declared first (see
  674. os-include/devices/timer.jch.patch). The supplied include/sys/time.h
  675. file works this way.  You can apply the patches with the program patch
  676. or by hand. The original devices/timer.h file is copyrighted by
  677. Commodore-Amiga and not included, but here is the patch:
  678.  
  679. + #ifndef _SYS_TIME_H_
  680. + /* Use whatever was included first, standard (sys/time.h) or Amiga
  681. +  * includes (jch). */
  682.   struct timeval {
  683.       ULONG tv_secs;
  684.       ULONG tv_micro;
  685.   };
  686. + #else
  687. + #define tv_secs  tv_sec
  688. + #define tv_micro tv_usec
  689. + #endif
  690.  
  691. The sys/types.h defined BPTR causing conflicts with Amiga includes. I
  692. removed the BPTR definition from sys/types.h and sys/proc.h. In
  693. gcc233, there was no such definition either.
  694.  
  695. I moved the ixemul.h file from include/ to the ixemlib/library/
  696. directory. The ixemlib/ directory could contain the ixemul.library
  697. sources. In the ixemul source tree, ixemul.h is found in the library/
  698. directory.  Furthermore I patched it so that it is now able to compile
  699. a working ixconfig. It was broken (because of the broken ixemul.h) in
  700. gcc252/3/4.  It previously worked in gcc233 but didn't provide the -e
  701. option. The ixemlib/library/version.h is an empty fake. I don't have a
  702. newer ixemul.h file.
  703.  
  704. There's yet another minor patch I'd like to suggest:
  705. *** include/stdlib.h.orig    Mon Aug 10 15:28:54 1992
  706. --- include/stdlib.h    Fri Dec 09 17:12:38 1993
  707. ***************
  708. *** 72,76 ****
  709. --- 72,80 ----
  710.   void    *calloc __P((size_t, size_t));
  711.   div_t     div __P((int, int));
  712. + #if 0
  713.   void volatile exit __P((int));
  714. + #else /* new ANSI-C interpretation */
  715. + typedef void exit_t __P((int)); volatile exit_t exit;
  716. + #endif
  717.   void     free __P((void *));
  718.   char    *getenv __P((const char *));
  719.  
  720. ===============
  721. Ld (GNU linker)
  722. ===============
  723.  
  724. Starting from 2.5.8 release, ld behavior over symbols has changed. Default is
  725. now to strip all symbols from generated executable ONLY if environment variable
  726. LDSTRIP is set (to whatever you want). Otherwise, '-s' flag will strip symbols,
  727. as usual.
  728. Also packing of uninitialized data will be done automatically if LDSHORTDATA is
  729. set (to whatever you want).
  730. Ld also knows about -chip and -fast keywords, gcc will soon handle them
  731. directly.
  732. Ld is using now flavors, which are generated depending on gcc flags:
  733.  
  734. Gcc option    Flavor passed to ld
  735. -m68020        -fl libm020
  736. -noixemul    -fl libnix
  737. -resident    -fl libb
  738.  
  739. Thus ld when searching for libraries, add to search library path those flavors,
  740. in alphabetical order. Normal search path is /gnu/lib, and if for example you
  741. want to compile using -m68020 -noixemul ld will look for libgcc.a in:
  742.     /gnu/lib/libm020/libnix
  743. first, then will reduce flavors, one by one, if it can't find required library
  744. in flavor's expanded path. This means that it will try to find libgcc.a in:
  745.     /gnu/lib/libm020
  746. and in  /gnu/lib/. because libgcc.a exists in /gnu/lib/libm020, ld will take
  747. this one.
  748.  
  749. There is as for now 8 possibilities:
  750.  
  751.     Flavors        Search path
  752. libb libm020 libnix
  753.  0      0      0    /gnu/lib/            normal
  754.  0      0      1    /gnu/lib/libnix/        non-ixemul
  755.  0      1      0    /gnu/lib/libm020/        normal 68020
  756.  0      1      1    /gnu/lib/libm020/libnix/    non-ixemul 68020
  757.  1      0      0    /gnu/lib/libb/            baserel
  758.  1      0      1    /gnu/lib/libb/libnix/        baserel non-ixemul
  759.  1      1      0    /gnu/lib/libb/libm020/        baserel 68020
  760.  1      1      1    /gnu/lib/libb/libm020/libnix/    baserel 68020 non-ix
  761.  
  762. Using this approach makes adding flavors pretty easily, if someone wants for
  763. example to add 68881 libraries, a new flavor will hve to be created, libm881,
  764. and thus maximum level flavor search path would be:
  765. /gnu/lib/libb/libm020/libm881/libnix, which can be translated in english as:
  766. "I want a base-relative library compiled using Motorola 68020 and coprocessor
  767. 68881, not using ixemul.library".
  768.  
  769. =====================
  770. gcc and its "pragmas"
  771. =====================
  772.  
  773. From Gunther Nikl:
  774.  
  775. Accessing operating-system functions on the amiga requires to pass arguments
  776. in specific processor registers. C, however, uses a different calling convention:
  777. it pushes all arguments in reverse order onto the stack, calls the function and
  778. finally removes the arguments from the stack by simply correcting the stack pointer.
  779. One solution to interface C and the calling convention for the system-functions are
  780. so called "glue"-functions that convert arguments passed on the stack into the
  781. os-function convention. These glue routines are located for all system libraries
  782. in a link library named libamiga.a. Obviously this method is inefficient. Most
  783. amiga c-compilers have the capability of in-line calls to os functions using
  784. a c language extension "#pragma". The format of a pragma statement and file names
  785. differ from compiler to compiler. gcc supports in-line calls too but not with
  786. pragmas. the gcc solution is based on the fact that gcc is able to integrate small
  787. functions into the caller. This method is known from c++ as "inlining". Thus
  788. functions that are declared "inline" (peferable in conjunction with the keyword
  789. static or extern but see the next chapter) get integrated. As you can see writing
  790. programs that compile with several compilers and use its capability of making
  791. in-line calls to libraries is a tricky thing.
  792.  
  793. To get programs more portable between amiga c-compilers a new set of include files
  794. would be helpful that hide the diffrent methods for in-line calls from the user.
  795. These files are located in a drawer called proto eg. "proto/exec.h". Instead of
  796. writing (only an example!):
  797.  
  798.     #include <clib/exec_protos.h>
  799.     #ifdef __GNUC__
  800.     #include <inline/exec.h>
  801.     #endif
  802.  
  803. now the following should be used:
  804.  
  805.     #include <proto/exec.h>
  806.  
  807. to achieve the same result! Nice, isn't it? The general rule for the all files is:
  808.  
  809.     #include <proto/xxx.h>
  810.  
  811. with "xxx" replaced with the first part of a clib proto-headers name eg.
  812. "exec_protos.h" becomes "exec.h"
  813.  
  814. In general each file first includes its function prototype header then the compiler
  815. specific "pragma" header and finally declares the library base extern. The gcc files
  816. are in the following format:
  817.  
  818.     (1) include some C= headers to prevent errors with gcc
  819.     (2) include the function prototypes from the clib drawer
  820.     (3) include the inline header if this is not disabled and if optimizing
  821.     (4) declare the library base extern if its not disabled
  822.  
  823. Step 3 will only be executed if gcc is optimizing. Otherwise the compiler won't
  824. integrate any function. Even when optimizing it could be not desired to include
  825. the inline header because it requires some amount of memory and the compile time
  826. enlarges significantly. Therefore step 3 can be disabled with:
  827.  
  828.     - a define on the commandline "-D__NOINLINES__"
  829.             or
  830.     - a define before the proto headers are included "#define __NOINLINES__"
  831.  
  832. Declaring the library base as an external variable can disabled with a define in
  833. the same way. The define is called "__NOLIBBASE__". This define can be useful if
  834. its not desired to have the library base declared extern.
  835.  
  836. Using the new proto headers has some advantages then using the clib and inline
  837. files by itself:
  838.  
  839.     (1) better compatibility with SAS/C. It should be much easier to compile
  840.         programs developed for SAS/C with gcc - almost ;) no need to adjust
  841.         includes
  842.     (2) almost ;) optimal code because depending on the optimization level
  843.         the best suited include set will be used
  844.     (3) internal compiler specific requirements are hidden from the user
  845.  
  846. For the exec.library the proto header has one additional goodie: it "implements"
  847. SAS/C "__USE_SYSBASE". Defining this forces to evaluate the absolute address 4
  848. every time the library base for the exec.library is required. In this case no
  849. global library base is necessary but it must be noted that programs compiled with
  850. this option enabled can have performance problems because AbsExecBase is located
  851. in Chip-Memory. Be aware: if using __USE_SYSBASE its *NOT* legal to declare or
  852. define SysBase! If you do so strange things may happen ... Please note that some
  853. function in libamiga.a require a global "SysBase" so that those functions cannot
  854. be used.
  855.  
  856. Some problems still remain but these restrictions come from the inline technique.
  857. Library bases have to be global due to the nature of the inlines. SAS/C, however,
  858. is able to use local variables or structure elements as library bases. In this case
  859. the library bases has to be made global for gcc.
  860.  
  861. inline headers
  862.  
  863. One major advantage of gcc is its ability to integrate simple functions into the
  864. caller. To direct the compiler to inline a function the keyword "inline" in
  865. combination with "static" or "extern" can be used. Previous version of the inlines
  866. used static in the definition. This had the effect that functions compiled to
  867. assembler if optimization is disabled. The new inline headers use extern definitions.
  868. Functions defined inline and extern can be considered as macros. That means the
  869. definition is only used for inlining thus requiring linking with a library containing
  870. stubs.
  871.